Reference for application configuration

You can configure your Kanzi application:

• In the C++ application in the onConfigure() function.
• In application.cfg by setting the parameters for Kanzi Studio projects with or without C++ application.

While you can configure your Kanzi application in the onConfigure() function, in application.cfg you can configure some parameters without recompiling your application or even without a C++ application. The configuration you specify in application.cfg overrides the configuration you specify in onConfigure().

For example, in application.cfg you can tell your Kanzi application which .kzb binary to load, enable performance information in your application, and set how many threads you want to use for loading the application resources.

Setting which application.cfg to use

When you have more than one Kanzi application executable file in a directory you can specify a separate configuration file for each executable.

To set which application.cfg to use:

• When running your Kanzi application from the command line enter the name of the application executable file followed by the -config flag, and the name of the configuration file.
  For example, to run a Kanzi application named MyApplication with the myConfiguration.cfg file use
  

  MyApplication.exe -config=myConfiguration.cfg

• To specify in the C++ application of your Kanzi application which application.cfg you want to use, in the onConfigure() function use
  

  configuration.configurationName = "myConfiguration.cfg"

Using the application.cfg

To configure your Kanzi application using application.cfg, create an application.cfg file that contains the parameter names and their values in:

• <ProjectName>/Application Player if you have a Kanzi Studio project without a C++ application
• <ProjectName>/Application/bin if you have a Kanzi Studio project with a C++ application

When you launch your Kanzi application, the application uses the parameters in the application.cfg to configure your application.

Show the performance information

You can enable the display of Performance HUD that shows the performance information for your Kanzi application. Use Kanzi's Performance HUD to see how your application performs on target devices and to find bottlenecks and areas for improvement.

• Frame duration shows the time in milliseconds it took to render a frame. The top value in the Frame duration graph shows the longest, and the bottom value the average time it took to render a frame during the last 300 frames.
  Use this information to identify performance bottlenecks in your Kanzi application. For example, you can use it to find out how to improve the performance of your application by distributing rendering across several frames. See Distributing rendering across several frames.
  
• Batch count shows how many individual draw calls were executed (glDrawElements and glDrawArrays).
  You can access the batch count using the Kanzi Engine API by calling getBatchCount().
  The top value in the Batch count graph shows the highest number of batches during the last 300 frames, and the bottom value the number of batches in the last frame.
  
• Triangle count shows how many individual triangles were drawn in total during a frame.
  You can access the triangle count in the Kanzi Engine API by calling getTriangleCount().
• Texture switches shows how many times new texture was bound to GPU.
  You can access the texture switch count in the Kanzi Engine API by calling getTextureSwitchCount().
• Framebuffer object (FBO) switches shows how many framebuffer objects were bound to GPU. See Rendering best practices.
  You can access the buffer switch count in the Kanzi Engine API by calling getFramebufferSwitchCount().
• Shader shows how many times a new shader was bound for the newly applied batch and how many individual shader uniforms were sent for the last frame. See Reducing shader switches.
  You can access the shader switch count in the Kanzi Engine API by calling getShaderSwitchCount().
  You can access the uniforms sent in the Kanzi Engine API by calling getUniformSendCount().
• Buffer switches shows how many vertex, index, and uniform buffer objects were bound to GPU.
  You can access the buffer switch count in the Kanzi Engine API by calling getBufferSwitchCount().
• Buffer/texture data updates shows how many times new vertex buffer or texture data was uploaded to the GPU. If the same buffer is accessed for write and read operations, these heavyweight operations can cause delay in GPU execution. The ideal value is 0. For example, this value can increase when the text glyph cache needs frequent updates. In this case, to decrease the value reduce the Font Size.
  You can access this in the Kanzi Engine API by calling getHeavyweightCallCount().
• View camera shows which Camera node is used for displaying the scene in your application.
• Resource memory consumption shows how much VRAM and RAM your Kanzi application uses.
• Animation player shows the current time in your application.

See Best practices.

Show the Log window

You can enable the printing of the application log messages to the application window.

To display the performance information of your application, see Show the performance information.

Size of the glyph cache texture

When you use a Text BlockKanzi creates a glyph cache texture for every font and font size combination. You can set the height and width of glyph cache textures to adjust the size of the glyph cache texture either when it gets full, or to optimize the performance of your Kanzi application.

Because larger glyph cache textures use more VRAM, try different sizes before you set the final size . The upper limit of the glyph cache texture size depends on the GPU, but usually it is 2048 by 2048 pixels. The default size of the glyph cache texture is 512 by 512 pixels.

Kanzi applies the size of the glyph cache texture to all glyph cache textures.

Loading preferences

When users run your Kanzi application in an environment with a multi-core processor, Kanzi automatically uses multiple CPU cores to load the GPU resources in the .kzb files to RAM. See Loading resources in parallel.

GPU resources Kanzi loads in parallel include all types of textures, shaders, and meshes. To deploy these resources from RAM to GPU memory and to load prefab templates, Kanzi always uses the main thread. See Images and textures best practices, Shaders best practices, Meshes best practices.

Maximum number of resources processed by the loading threads

You can set the maximum number of resources that the loading threads process at the same time. By increasing the number of resources you can speed up the loading, but at the same time you increase the peak memory use during loading because you can load more resources to the memory before they are deployed to the GPU.

# Sets the maximum number of resources processed by the loading
# threads to the number of loading threads + 1. This is the default value.
MaxPendingResources = 0

# Sets the maximum number of resources processed by the loading
# threads to 20 resources.
MaxPendingResources = 20

// Sets the maximum number of resources processed by the loading
// threads to the number of loading threads + 1. This is the default value.
configuration.maxPendingResources = 0;

// Sets the maximum number of resources processed by the loading
// threads to 20 resources.
configuration.maxPendingResources = 20;

Surface properties

Surface properties control the properties of the hardware accelerated graphics surface on which Kanzi renders. They control the relation between image quality and rendering speed. The surface properties you set are considered requests to be matched by the graphics system of the target hardware. Whether a given request is considered an upper bound, a lower bound, or an exact value is platform dependent.

The default values of surface properties are platform dependent. You can get them by calling kzsSurfaceGetDefaultProperties().

Default display when running the application in full-screen mode

When you run your Kanzi application in full-screen mode on a system with more than one display, you can set the default display where your Kanzi application window appears.

Note that in order to use the default application display, you have to set the window style of your Kanzi application to full-screen. See Window style of the application and KzsWindowProperties.

Position and size of the application window

You can set the position of the application on the screen relative to the upper-left corner of the screen and the size of the application window in pixels. The default size of the window is 640x480 pixels and center of the device screen.

To change the style of the window, see Window style of the application.

Memory mapped loading

When running your Kanzi application on an operating system that supports memory mapping of files, you can enable memory mapped loading for the .kzb files your Kanzi application uses. When you enable memory mapped loading you can reduce the loading times of your Kanzi application because it reduces the amount of file accesses.

Memory mapping of files is supported, for example, on Windows, Linux, and QNX operating systems. Before enabling memory mapped loading, check that it is supported on the platform running your Kanzi application.

To check whether memory mapped loading is supported on your platform, call the kzsMemoryMappedFileIsSupported() function. The function returns True if memory mapped loading is supported, and False if it is not supported.

If you enable memory mapped loading on a platform that does not support this feature, Kanzi shows a warning and uses regular file access for loading the .kzb files.

Window style of the application

You can set the style of the window of your Kanzi application. Besides the default window with a border that users can resize, you can set your Kanzi application to launch in a window without a border, in a window of fixed size, and in a window that occupies the entire device screen.

To set the position and size of the application window, see Position and size of the application window.

Maximum FPS

You can limit the number of frames rendered per second by setting the maximum frame rate. See Show the performance information.

Kzb binary the application loads

You can set which .kzb binary or binary configuration file your Kanzi application loads when a you launch your Kanzi application.

See Using .kzb binaries.

See also

Best practices

Loading resources in parallel

Using .kzb binaries

Open topic with navigation